Change the .NET tool tutorial by adegeo · Pull Request #52952 · dotnet/docs

adegeo · 2026-04-08T21:57:20Z

Summary

Replaces microsoft.botsay with the new dotnet-env example in .NET CLI tool tutorials.
Updates the content for .NET 10.
Revises all code, commands, and sample output to match the new tool.
Uses a more practical example that reports runtime, OS, and environment info.

Major changes include:

Tutorial and Example Tool Updates

Replaced all references to the old microsoft.botsay tool with the new dotnet-env tool, including project names, command names, and sample outputs. The new tool displays .NET runtime info, OS details, and key environment variables. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11]
Updated code snippets and project file examples to match the new dotnet-env tool, including new sample outputs and configuration. [1] [2]

Version and Prerequisite Modernization

Updated all tutorials to reference .NET 10 SDK (and .NET 8 for applicability), removing references to older SDKs and runtimes. [1] [2] [3]
Clarified and updated prerequisites, removing outdated requirements for .NET Core 2.1 runtime.

Usability and Clarity Improvements

Improved explanations, updated notes, and clarified instructions throughout the tutorials to reflect the new tool and modern .NET practices. [1] [2] [3] [4]
Updated all sample manifest files and outputs to use dotnet-env as the installed tool. [1] [2] [3]

Fixes #43983

Internal previews

📄 File	🔗 Preview link
docs/core/tools/global-tools-how-to-create.md	Tutorial: Create a .NET tool using the .NET CLI
docs/core/tools/global-tools-how-to-use.md	"Tutorial: Install and use a .NET global tool"
docs/core/tools/local-tools-how-to-use.md	Tutorial: Install and use a .NET local tool using the .NET CLI

Co-authored-by: Copilot <[email protected]>

Rename microsoft.botsay to �otsay across the three-part .NET tool tutorial series to avoid teaching users to create packages with reserved company name prefixes on NuGet.org. - global-tools-how-to-create.md: rename project/folder/namespace/package references; add NOTE about avoiding company-owned NuGet prefixes - global-tools-how-to-use.md: update all install/uninstall/dnx commands and output blocks - local-tools-how-to-use.md: update folder, install, manifest JSON, output blocks, and tool list output Fixes #43983 Co-authored-by: Copilot <[email protected]>

Replace the novelty `botsay` ASCII robot tool with `dotnet-env`, a practical tool that reports .NET runtime info, OS details, and key environment variable settings. Changes span the three-part tutorial series and add proper snippet files. - global-tools-how-to-create.md: replace all botsay code and prose with dotnet-env implementation; add snippet reference via :::code:::; add verified dotnet run output block - global-tools-how-to-use.md: update all install/uninstall/dnx commands; fix "may" → "might"; fix "Nuget.org" → "NuGet.org" - local-tools-how-to-use.md: update all commands, manifest JSON, output blocks; remove stale .NET Core 2.1 prerequisite - snippets/global-tools-how-to-create/csharp/Program.cs: new snippet file with four region markers (full-program, main-method, show-info-method, using-directives) - snippets/global-tools-how-to-create/csharp/dotnet-env.csproj: new project file for snippet verification Co-authored-by: Copilot <[email protected]>

- Update all 'applies to' banners from .NET Core 2.1/.NET Core 3.0 to .NET 8 - Update prerequisites link and prose from .NET SDK 6.0 to .NET 8 - Update dotnet new -f flag from net6.0 to net8.0 - Update multi-target example from net8.0;net6.0 to net9.0;net8.0 - Update sample output Runtime section from 6.0.36 to 8.0.14 - Update project file TargetFramework from net6.0 to net8.0 in both article and snippet Co-authored-by: Copilot <[email protected]>

- dotnet new command: -f net8.0 -> -f net10.0 - Prerequisites: link and prose updated to .NET SDK 10.0 - NOTE text: 'targets .NET 8' -> 'targets .NET 10' - Multi-target example: net9.0;net8.0 -> net10.0;net8.0 - Project file XML in prose: net8.0 -> net10.0 - Sample output: updated to real .NET 10.0.4 / win-x64 output (verified via dotnet run) - Snippet .csproj: net8.0 -> net10.0 - Minimum requirement ('applies to' banner and historical notes) unchanged Co-authored-by: Copilot <[email protected]>

…ed repos)" This reverts commit 53b549a.

Copilot

Pull request overview

Updates the .NET tool tutorial series to use a new sample tool (dotnet-env) and refreshes the tutorials for newer .NET versions.

Changes:

Replaces the prior microsoft.botsay sample with a new dotnet-env tool and updates commands/output throughout the global and local tool tutorials.
Adds new C# snippet sources for the tool (Program.cs) and packing configuration (dotnet-env.csproj) and references them from the create tutorial.
Refreshes tutorial metadata (dates, applies-to), and modernizes some wording.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/core/tools/snippets/global-tools-how-to-create/csharp/Program.cs	Adds the new sample tool implementation used by the tutorial.
docs/core/tools/snippets/global-tools-how-to-create/csharp/dotnet-env.csproj	Adds tool packing settings and snippet regions referenced by the tutorial.
docs/core/tools/global-tools-how-to-create.md	Switches the “create” tutorial to the new `dotnet-env` sample and snippet-based code inclusion.
docs/core/tools/global-tools-how-to-use.md	Updates global tool usage steps to the new sample and includes `dnx`-based run guidance.
docs/core/tools/local-tools-how-to-use.md	Updates local tool usage steps to the new sample and new command examples.

Comments suppressed due to low confidence (1)

docs/core/tools/global-tools-how-to-use.md:21

The article says it applies to .NET 8 SDK and later, but the tutorial content relies on .NET 10 (dnx starting with .NET 10.0.100). Align the applies to line with the actual minimum SDK needed for the steps, or clearly split steps into .NET 8-compatible vs .NET 10-only.

**This article applies to:** ✔️ .NET 8 SDK and later versions

This tutorial teaches you how to install and use a global tool. You use a tool that you create in the [first tutorial of this series](global-tools-how-to-create.md).

## Prerequisites

* Complete the [first tutorial of this series](global-tools-how-to-create.md).
* .NET 10.0.100 SDK or later (for `dnx`) - optional but recommended.

## Run the tool without installation (recommended)

Starting with .NET 10.0.100, you can run .NET tools without permanent installation using [`dnx`](dotnet-tool-exec.md):

Co-authored-by: Andy (Steve) De George <[email protected]>

gewarren · 2026-04-23T23:10:30Z

+- [.NET SDK 10.0](https://dotnet.microsoft.com/download/dotnet/10.0) or a later version.

-  This tutorial uses .NET SDK 6.0, but global tools are available starting in .NET Core SDK 2.1. Local tools are available starting in .NET Core SDK 3.0.
+  This tutorial uses .NET SDK 10.0. Global tools are available starting in .NET Core SDK 2.1, and local tools are available starting in .NET Core SDK 3.0.


Do we even need this paragraph anymore?

gewarren · 2026-04-23T23:11:18Z

+   - `ShowInfo` displays three sections of information:
+     - **Runtime** — the .NET version, framework description, and runtime identifier, using `Environment.Version` and `RuntimeInformation`.
+     - **System** — OS description, architecture, machine name, and processor count.
+     - **Environment Variables** — six key .NET-related variables (`DOTNET_ROOT`, `DOTNET_HOST_PATH`, `DOTNET_CLI_HOME`, `DOTNET_NOLOGO`, `NUGET_PACKAGES`, and `DOTNET_ENVIRONMENT`), showing `(not set)` for any that aren't configured.


Suggested change

- **Environment Variables** — six key .NET-related variables (`DOTNET_ROOT`, `DOTNET_HOST_PATH`, `DOTNET_CLI_HOME`, `DOTNET_NOLOGO`, `NUGET_PACKAGES`, and `DOTNET_ENVIRONMENT`), showing `(not set)` for any that aren't configured.

- **Environment variables** — six key .NET-related variables (`DOTNET_ROOT`, `DOTNET_HOST_PATH`, `DOTNET_CLI_HOME`, `DOTNET_NOLOGO`, `NUGET_PACKAGES`, and `DOTNET_ENVIRONMENT`), showing `(not set)` for any that aren't configured.

gewarren · 2026-04-23T23:17:00Z

+var versionString = Assembly.GetEntryAssembly()?
+                        .GetCustomAttribute<AssemblyInformationalVersionAttribute>()?
+                        .InformationalVersion
+                        .ToString();
+
+Console.WriteLine($"dotnet-env v{versionString}");


Delete? It's duplicated in ShowInfo().

gewarren · 2026-04-23T23:17:14Z

-       }
-   }
-   ```
+   - The startup code checks displays the version of the command and then calls the `ShowInfo` method.


Suggested change

- The startup code checks displays the version of the command and then calls the `ShowInfo` method.

- The startup code checks the version of the command and then calls the `ShowInfo` method.

adegeo and others added 6 commits April 8, 2026 09:12

chore: ignore .squad/ directory (personal/local, not for shared repos)

53b549a

Co-authored-by: Copilot <[email protected]>

Remove main method from program

205d549

dotnetrepoman Bot added this to the April 2026 milestone Apr 8, 2026

dotnet-policy-service Bot added dotnet-fundamentals/svc dotnet-cli/subsvc labels Apr 8, 2026

adegeo added 3 commits April 8, 2026 15:58

Adjust snippet ids

82deab3

REALLY fix snippet id

6d46f2a

Revert "chore: ignore .squad/ directory (personal/local, not for shar…

421eafd

…ed repos)" This reverts commit 53b549a.

adegeo marked this pull request as ready for review April 10, 2026 21:46

adegeo requested review from a team and meaghanlewis as code owners April 10, 2026 21:46

adegeo requested review from Copilot and gewarren April 10, 2026 21:46

adegeo assigned gewarren Apr 10, 2026

Copilot started reviewing on behalf of adegeo April 10, 2026 21:47 View session

Copilot AI reviewed Apr 10, 2026

View reviewed changes

adegeo commented Apr 23, 2026

View reviewed changes

Comment thread docs/core/tools/snippets/global-tools-how-to-create/csharp/Program.cs Outdated

adegeo commented Apr 23, 2026

View reviewed changes

Comment thread docs/core/tools/global-tools-how-to-create.md Outdated

adegeo added 2 commits April 23, 2026 12:19

Apply suggestions from code review

be2271b

Co-authored-by: Andy (Steve) De George <[email protected]>

Fix github bad edit

6897a6b

gewarren reviewed Apr 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Change the .NET tool tutorial#52952

Change the .NET tool tutorial#52952
adegeo wants to merge 11 commits intomainfrom
adegeo/43983/tool

adegeo commented Apr 8, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gewarren Apr 23, 2026

Uh oh!

gewarren Apr 23, 2026

Uh oh!

gewarren Apr 23, 2026

Uh oh!

gewarren Apr 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	- Environment Variables — six key .NET-related variables (`DOTNET_ROOT`, `DOTNET_HOST_PATH`, `DOTNET_CLI_HOME`, `DOTNET_NOLOGO`, `NUGET_PACKAGES`, and `DOTNET_ENVIRONMENT`), showing `(not set)` for any that aren't configured.
	- Environment variables — six key .NET-related variables (`DOTNET_ROOT`, `DOTNET_HOST_PATH`, `DOTNET_CLI_HOME`, `DOTNET_NOLOGO`, `NUGET_PACKAGES`, and `DOTNET_ENVIRONMENT`), showing `(not set)` for any that aren't configured.

	- The startup code checks displays the version of the command and then calls the `ShowInfo` method.
	- The startup code checks the version of the command and then calls the `ShowInfo` method.

Conversation

adegeo commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Tutorial and Example Tool Updates

Version and Prerequisite Modernization

Usability and Clarity Improvements

Internal previews

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gewarren Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

gewarren Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

gewarren Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

gewarren Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

adegeo commented Apr 8, 2026 •

edited

Loading